/// \file A3200SFRecording.h
/// \brief Contains functions to configure Sensor Fusion data recording and retrieve data recorded during a data recording session.
///
/// Copyright (c) Aerotech, Inc. 2011-2015.
///

#include "A3200SFRecordingInfo.h"
#include "A3200CommonTypes.h"
#include "A3200CommonStructures.h"

#ifndef __A3200_SFRECORDING__
#define __A3200_SFRECORDING__

#ifdef __cplusplus
extern "C" {
#endif

/// \defgroup sensorfusiondatarecording Sensor Fusion Data Recording Functions
/// @{

/// \brief The handle to the Sensor Fusion data recording Configuration.
///
/// This is used to hold the Sensor Fusion data recording Configuration.
typedef void* SFRecordingHandle;

/// \brief The data recording status struct.
///
/// This struct will be filled in when checking the status of a currently executing data recording session.
typedef struct tagSFRecordingStatus {
	DWORD pointsRecorded; ///< The number of points recorded during the data recording session
	DATARECORDINGFLAGS statusFlags; ///< The status flags, as defined in A3200CommonStructures.h
	DWORD spare[4]; ///< Reserved for future expansion
} SFRecordingStatus;

/// \brief Creates a new Sensor Fusion data recording configuration.
///
/// This function creates a new Sensor Fusion data recording configuration object. This object can then be used to configure data recording (specifying signals to record, buffer size, etc.). It is important to call A3200SFRecordingFreeConfig() when one is finished using the handle, or else memory leaks will occur.
/// \param[out] pRecordingHandle A pointer to a handle for the Sensor Fusion data recording configuration object
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingCreateConfig(SFRecordingHandle* pRecordingHandle);

/// \brief Frees a Sensor Fusion data recording configuration object.
///
/// This function cleans up a Sensor Fusion data recording configuration object that was created by A3200SFRecordingCreateConfig(). Calling this function is necessary in order to clean up resources (memory) used by the configuration object.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingFreeConfig(SFRecordingHandle recordingHandle);

/// \brief Configures the initial trigger to be triggered immediately.
///
/// This function configures the start trigger to be triggered immediately after a data recording session begins.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingStartTriggerImmediately(SFRecordingHandle recordingHandle);

/// \brief Configures the start trigger to be triggered on a digital input edge.
///
/// This function configures the start trigger to be triggered on a digital input rising and/or falling edge.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] cardIndex The Sensor Fusion card number where the digital input is located
/// \param[in] bitNumber The bit number of the digital input
/// \param[in] edgeKind The kind of edge activity that triggers the start condition
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingStartOnDigitalInput(SFRecordingHandle recordingHandle, DWORD cardIndex, DWORD bitNumber, EDGE edgeKind);

/// \brief Configures the start trigger to be triggered on a digital output edge.
///
/// This function configures the start trigger to be triggered on a digital output rising and/or falling edge.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] cardIndex The Sensor Fusion card number where the digital output is located
/// \param[in] bitNumber The bit number of the digital output
/// \param[in] edgeKind The kind of edge activity that triggers the start condition
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingStartOnDigitalOutput(SFRecordingHandle recordingHandle, DWORD cardIndex, DWORD bitNumber, EDGE edgeKind);

/// \brief Configures the start trigger to be triggered on a PSO event.
///
/// This function configures the start trigger to be triggered on a PSO event.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] cardIndex The Sensor Fusion card index where the PSO card is located
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingStartOnPSOEvent(SFRecordingHandle recordingHandle, DWORD cardIndex);

/// \brief Configures the start trigger to be triggered on a PSO output event.
///
/// This function configures the start trigger to be triggered on a PSO output event.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] cardIndex The Sensor Fusion card index where the PSO card is located
/// \param[in] outputNumber The PSO output number
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingStartOnPSOOutput(SFRecordingHandle recordingHandle, DWORD cardIndex, DWORD outputNumber);

/// \brief Configures the start trigger to be triggered on a PSO window event.
///
/// This function configures the start trigger to be triggered on a PSO window event.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] cardIndex The Sensor Fusion card index where the PSO card is located
/// \param[in] windowNumber The PSO window number
/// \param[in] windowEventKind The kind of window activity that triggers the start condition
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingStartOnPSOWindow(SFRecordingHandle recordingHandle, DWORD cardIndex, DWORD windowNumber, WINDOWEVENT windowEventKind);

/// \brief Configures the time period that elapses between the collection of a set of samples.
///
/// This function specifies the time period that elapses between the collection of a set of samples.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] period The collection period
/// \param[in] timeUnit The units component of the specified collection period
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingCollectOnInterval(SFRecordingHandle recordingHandle, double period, TIMEUNIT timeUnit);

/// \brief Configures the collection trigger to be triggered on a digital input edge.
///
/// This function configures the collection trigger to be triggered on a digital input rising and/or falling edge.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] cardIndex The Sensor Fusion card number where the digital input is located
/// \param[in] bitNumber The bit number of the digital input
/// \param[in] edgeKind The kind of edge activity that triggers the start condition
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingCollectOnDigitalInput(SFRecordingHandle recordingHandle, DWORD cardIndex, DWORD bitNumber, EDGE edgeKind);

/// \brief Configures the collection trigger to be triggered on a digital output edge.
///
/// This function configures the collection trigger to be triggered on a digital output rising and/or falling edge.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] cardIndex The Sensor Fusion card number where the digital output is located
/// \param[in] bitNumber The bit number of the digital output
/// \param[in] edgeKind The kind of edge activity that triggers the start condition
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingCollectOnDigitalOutput(SFRecordingHandle recordingHandle, DWORD cardIndex, DWORD bitNumber, EDGE edgeKind);

/// \brief Configures the collection trigger to be triggered on a PSO event.
///
/// This function configures the collection trigger to be triggered on a PSO event.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] cardIndex The Sensor Fusion card index where the PSO card is located
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingCollectOnPSOEvent(SFRecordingHandle recordingHandle, DWORD cardIndex);

/// \brief Configures the collection trigger to be triggered on a PSO output event.
///
/// This function configures the collection trigger to be triggered on a PSO output event.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] cardIndex The Sensor Fusion card index where the PSO card is located
/// \param[in] outputNumber The PSO output number
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingCollectOnPSOOutput(SFRecordingHandle recordingHandle, DWORD cardIndex, DWORD outputNumber);

/// \brief Configures the collection trigger to be triggered on a PSO window event.
///
/// This function configures the collection trigger to be triggered on a PSO window event.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] cardIndex The Sensor Fusion card index where the PSO card is located
/// \param[in] windowNumber The PSO window number
/// \param[in] windowEventKind The kind of window activity that triggers the start condition
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingCollectOnPSOWindow(SFRecordingHandle recordingHandle, DWORD cardIndex, DWORD windowNumber, WINDOWEVENT windowEventKind);

/// \brief Configures the trigger divisor for a specific Sensor Fusion card.
///
/// This function configures the trigger divisor for a specific Sensor Fusion card.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] cardIndex The Sensor Fusion card number on which to apply the trigger divisor value
/// \param[in] divisor The value of the trigger divisor
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingSetTriggerDivisor(SFRecordingHandle recordingHandle, DWORD cardIndex, DWORD divisor);

/// \brief Configures the size of the data buffer on the Sensor Fusion.
///
/// This function configures the sizes of the data buffer used to store data collected during a data recording session.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] bufferSize The size of the data recording buffer
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingSetBufferSize(SFRecordingHandle recordingHandle, DWORD bufferSize);

/// \brief Adds a signal to be recorded during a data recording session.
///
/// This function specifies a Sensor Fusion data item to collect when recording is triggered.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] signal The kind of data signal to collect
/// \param[in] cardIndex The Sensor Fusion card number on which to collect the data signal
/// \param[in] argument An optional argument that specifies additional data for the data signal to collect. A value of 0 means that the argument value is ignored.
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingAddSignal(SFRecordingHandle recordingHandle, SFRECORDINGSIGNAL signal, DWORD cardIndex, INT argument);

/// \brief Configures the data recording session to consume the specified task.
///
/// This function configures the task to use for the data recording session. To prevent the possibility of errors, no other programs or commands should be executed on the specified task while a data recording session is occurring.
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] taskId The task to consume
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingSetConsumedTask(SFRecordingHandle recordingHandle, TASKID taskId);

/// \brief Starts a data recording session with the specified configuration.
///
/// This function starts a data recording session with the specified configuration.
/// \param[in] handle The handle to the A3200
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingStart(A3200Handle handle, SFRecordingHandle recordingHandle);

/// \brief Retrieves status information about a currently executing data recording session.
///
/// This function retrieves status information about a currently executing data recording session.
/// \param[in] handle The handle to the A3200
/// \param[out] pStatus A pointer to a SFRecordingStatus struct to be filled in with current data recording status information
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingStatus(A3200Handle handle, SFRecordingStatus* pStatus);

/// \brief Stops a currently executing data recording session.
///
/// This function stops a currently executing data recording session.
/// \param[in] handle The handle to the A3200
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingStop(A3200Handle handle, SFRecordingHandle recordingHandle);

/// \brief Waits for the specified number of points to be recorded.
///
/// This function waits for the specified number of points to be recorded.
/// \param[in] handle The handle to the A3200
/// \param[in] points The number of points to wait for
/// \param[in] timeout The timeout to wait for in milliseconds.  -1 means to wait forever, 0 means to not wait.
/// \param[out] timedOut Whether the wait timed out or not. This parameter can be NULL if the timeout information is not desired.
/// \return TRUE on success, FALSE if an error occurred. Call A3200GetLastError() for more information.
BOOL DLLENTRYDECLARATION A3200SFRecordingWaitForData(A3200Handle handle, DWORD points, DWORD timeout, PBOOL timedOut);

/// \brief Retrieves the specified number of points collected during a data recording session.
///
/// This function retrieves the specified number of points collected for a signal during a data recording session.
/// In addition, recording times for each point can be retrieved from the "times" array.
/// This function waits until the specified number of points have been recorded and then retrieves the points.
/// \param[in] handle The handle to the A3200
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] signal The kind of data signal to retrieve
/// \param[in] cardIndex The Sensor Fusion card number on which to retrieve the points for the data signal
/// \param[in] argument An optional argument that specifies additional data for the points of the data signal
/// \param[in] pointsToRetrieve The number of points to retrieve
/// \param[out] points An array containing the requested points that were retrieved
BOOL DLLENTRYDECLARATION A3200SFRecordingGetData(A3200Handle handle, SFRecordingHandle recordingHandle, SFRECORDINGSIGNAL signal, DWORD cardIndex, INT argument, DWORD pointsToRetrieve, DOUBLE* points);

/// \brief Retrieves the recording times for a specified number of points.
///
/// This function retrieves the recording times for a specified number of points. This may be useful when the collection trigger is IO-based and the times when the collection trigger was triggered are desired.
/// This function waits until the specified number of points have been recorded and then retrieves the points.
/// \param[in] handle The handle to the A3200
/// \param[in] recordingHandle The handle to a Sensor Fusion data recording configuration object
/// \param[in] pointsToRetrieve The number of points to retrieve
/// \param[out] times An array containing the times when each point of data was collected
BOOL DLLENTRYDECLARATION A3200SFRecordingGetTimes(A3200Handle handle, SFRecordingHandle recordingHandle, DWORD pointsToRetrieve, DOUBLE* times);

/// @}

#ifdef __cplusplus
}
#endif

#endif __A3200_SFRECORDING__
